package sjtu.rfid.rri.services.io;

import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;

/**
 * 
 * This interface is a factory service for creating new Connection objects.
 * 
 * It takes several parameters.
 * 
 * The first one is a URL which takes the general form:
 * 
 * {scheme}:[{target}][{params}]
 * 
 * where {scheme} is the name of a protocol such as http}.
 * 
 * The {target} is normally some kind of network address.
 * 
 * Any {params} are formed as a series of equates of the form ";x=y". Example:
 * ";type=a".
 * 
 * An optional second parameter specifies a mode flag (@see AccessMode) that
 * indicates to the protocol handler the intentions of the calling code. The
 * options here specify if the connection is going to be read (READ), written
 * (WRITE), or both (READ_WRITE). The validity of these flag settings is
 * protocol dependent. For instance, a connection for a printer would not allow
 * read access, and would throw an IllegalArgumentException. If the mode
 * parameter is not specified, READ_WRITE is used by default.
 * 
 * An optional third parameter specifies a boolean flag that indicates if the
 * calling code can handle timeout exceptions. If this flag is set, the protocol
 * implementation may throw an InterruptedIOException when it detects a timeout
 * condition. This flag is only a hint to the protocol handler, and it does not
 * guarantee that such exceptions will actually be thrown. If this parameter is
 * not set, no timeout exceptions will be thrown.
 * 
 * 
 * @author jinghao
 * 
 */
public interface ConnectionFactory {

	/**
	 * Create and open a Connection.
	 * 
	 * @param name
	 *            The URL for the connection.
	 * @return A new Connection object.
	 * @throws IOException
	 */
	Connection open(String name) throws IOException;

	/**
	 * Create and open a Connection.
	 * 
	 * @param name
	 *            The URL for the connection.
	 * @param mode
	 *            The access mode.
	 * @return A new Connection object.
	 * @throws IOException
	 */
	Connection open(String name, AccessMode mode) throws IOException;

	/**
	 * Create and open a Connection.
	 * 
	 * @param name
	 *            The URL for the connection.
	 * @param mode
	 *            The access mode.
	 * @param timeouts
	 *            A flag to indicate that the caller wants timeout exceptions.
	 * @return A new Connection object.
	 * @throws IOException
	 */
	Connection open(String name, AccessMode mode, boolean timeouts)
			throws IOException;

	/**
	 * 
	 * @param name
	 *            The URL for the connection.
	 * @return An InputStream.
	 * @throws IOException
	 *             If some other kind of I/O error occurs.
	 */
	InputStream openInputStream(String name) throws IOException;

	/**
	 * 
	 * @param name
	 *            The URL for the connection.
	 * @return An OutputStream.
	 * @throws IOException
	 *             If some other kind of I/O error occurs.
	 */
	OutputStream openOutputStream(String name) throws IOException;

	/**
	 * create message consumer using default buffer size
	 * 
	 * @param is
	 *            InputStream
	 * @param listener
	 *            MessageListener
	 * @return
	 */
	Consumer createConsumer(InputStream is, MessageListener listener);

	/**
	 * create message consumer
	 * 
	 * @param is
	 *            InputStream
	 * @param listener
	 *            MessageListener
	 * @param buffersize
	 * @return
	 */
	Consumer createConsumer(InputStream is, MessageListener listener,
			int buffersize);

	/**
	 * Create a ServerConnection.
	 * 
	 * @param name
	 *            The URL for the server connection.
	 * @return A new ServerConnection object.
	 * @throws IOException
	 */
	ServerConnection createServerConnection(String name) throws IOException;

}
